3D Graphics Programming with QuickDraw 3D 1.5.4

Public Draw Context Methods

To write a drawing engine, you need to implement a number of drawing methods, pointers to which are contained in a draw context structure (of type TQADrawContext ). These functions are called whenever an application uses one of the drawing macros described earlier (in "Manipulating Draw Contexts" ). For example, when an application uses the QADrawPoint macro to draw a point in a draw context linked to your drawing engine, your engine's TQADrawPoint method is called.

A draw context structure is passed as the first parameter to all these draw context methods. This allows you to retrieve your draw context's private data, which is pointed to by the first field of that structure.

Most of the draw context methods declare the draw context structure passed to them as const , in which case you should not alter any fields of that structure. Only three methods are allowed to change fields of the draw context structure: TQASetFloat , TQASetInt , and TQASetPtr . Failure to heed the const declaration may cause any code calling your engine (including QuickDraw 3D) to fail.

Pointers to your drawing engine's public draw context methods are assigned to the fields of a draw context structure by your TQADrawPrivateNew method. See page [link] for details.

TQAGetFloat

A drawing engine must define a method to get a floating-point value of a draw context state variable.



 
typedef float (*TQAGetFloat) (

                     const TQADrawContext *drawContext, 

                     TQATagFloat tag);

drawContext: A draw context.
tag: A state variable tag.

DESCRIPTION

Your TQAGetFloat function should return, as its function result, the floating-point value of the draw context state variable specified by the drawContext and tag parameters. If you do not recognize or support the specified tag, your TQAGetFloat function should return the value 0.

TQASetFloat

A drawing engine must define a method to set a floating-point value for a draw context state variable.



 
typedef void (*TQASetFloat) (

                     TQADrawContext *drawContext, 

                     TQATagFloat tag, 

                     float newValue);

drawContext: A draw context.
tag: A state variable tag.
newValue: The new value of the specified state variable.

DESCRIPTION

Your TQASetFloat function should set the value of the draw context state variable specified by the drawContext and tag parameters to the floating-point value specified by the newValue parameter.

Your drawing engine must accept all possible values for the tag parameter. If you encounter a value in the tag parameter that you cannot recognize, you should do nothing. Similarly, you should do nothing if the tag parameter specifies a state variable for optional features your drawing engine does not support.

SPECIAL CONSIDERATIONS

If your TQASetFloat function needs to change one or more of the function pointers in the specified draw context, it must call the QARegisterDrawMethod function to do so. It should not directly change the fields of a draw context.

TQAGetInt

A drawing engine must define a method to get a long integer value of a draw context state variable.



 
typedef unsigned long (*TQAGetInt) ( 

                     const TQADrawContext *drawContext, 

                     TQATagInt tag);

drawContext: A draw context.
tag: A state variable tag.

DESCRIPTION

Your TQAGetInt function should return, as its function result, the long integer value of the draw context state variable specified by the drawContext and tag parameters. If you do not recognize or support the specified tag, your TQAGetInt function should return the value 0.

TQASetInt

A drawing engine must define a method to set a long integer value for a draw context state variable.



 
typedef void (*TQASetInt) (

                     TQADrawContext *drawContext, 

                     TQATagInt tag, 

                     unsigned long newValue);

drawContext: A draw context.
tag: A state variable tag.
newValue: The new value of the specified state variable.

DESCRIPTION

Your TQASetInt function should set the value of the draw context state variable specified by the drawContext and tag parameters to the long integer value specified by the newValue parameter.

SPECIAL CONSIDERATIONS

If your TQASetInt function needs to change one or more of the function pointers in the specified draw context, it must call the QARegisterDrawMethod function to do so. It should not directly change the fields of a draw context.

TQAGetPtr

A drawing engine must define a method to get a pointer value of a draw context state variable.



 
typedef void *(*TQAGetPtr) (

                     const TQADrawContext *drawContext, 

                     TQATagPtr tag);

drawContext: A draw context.
tag: A state variable tag.

DESCRIPTION

Your TQAGetPtr function should return, as its function result, the pointer value of the draw context state variable specified by the drawContext and tag parameters. If you do not recognize or support the specified tag, your TQAGetPtr function should return the value 0.

TQASetPtr

A drawing engine must define a method to set a pointer value for a draw context state variable.



 
typedef void (*TQASetPtr) (

                     TQADrawContext *drawContext, 

                     TQATagPtr tag, 

                     const void *newValue);

drawContext: A draw context.
tag: A state variable tag.
newValue: The new value of the specified state variable.

DESCRIPTION

Your TQASetPtr function should set the value of the draw context state variable specified by the drawContext and tag parameters to the pointer value specified by the newValue parameter.

SPECIAL CONSIDERATIONS

If your TQASetPtr function needs to change one or more of the function pointers in the specified draw context, it must call the QARegisterDrawMethod function to do so. It should not directly change the fields of a draw context.

TQADrawPoint

A drawing engine must define a method to draw a point.



 
typedef void (*TQADrawPoint) (

                     const TQADrawContext *drawContext, 

                     const TQAVGouraud *v);

drawContext: A draw context.
v: A Gouraud vertex.

DESCRIPTION

Your TQADrawPoint function should draw the single point specified by the v parameter to the draw context specified by the drawContext parameter. The size of the point is determined by the kQATag_Width state variable of the draw context.

TQADrawLine

A drawing engine must define a method to draw a line between two points.



 
typedef void (*TQADrawLine) (

                     const TQADrawContext *drawContext, 

                     const TQAVGouraud *v0, 

                     const TQAVGouraud *v1);

drawContext: A draw context.
v0: A Gouraud vertex.
v1: A Gouraud vertex.

DESCRIPTION

Your TQADrawLine function should draw the line specified by the v0 and v1 parameters to the draw context specified by the drawContext parameter. The size of the line is determined by the kQATag_Width state variable of the draw context. If the specified vertices have different colors, the line color is interpolated smoothly between the two vertex colors.

TQADrawTriGouraud

A drawing engine must define a method to draw Gouraud-shaded triangles.



 
typedef void (*TQADrawTriGouraud) ( 

                     const TQADrawContext *drawContext, 

                     const TQAVGouraud *v0, 

                     const TQAVGouraud *v1, 

                     const TQAVGouraud *v2, 

                     unsigned long flags);

drawContext: A draw context.
v0: A Gouraud vertex.
v1: A Gouraud vertex.
v2: A Gouraud vertex.
flags: A set of triangle flags. See "Triangle Flags Masks" for a complete description of the available flags.

DESCRIPTION

Your TQADrawTriGouraud function should draw the Gouraud-shaded triangle determined by the three points specified by the v0 , v1 , and v2 parameters into the draw context specified by the drawContext parameter. Features of the triangle are determined by the flags parameter. Currently, this parameter is used to specify an orientation for the triangle.

TQADrawTriTexture

A drawing engine may define a method to draw texture-mapped triangles. This method is optional and must be supported only by drawing engines that support texture mapping.



 
typedef void (*TQADrawTriTexture) ( 

                     const TQADrawContext *drawContext, 

                     const TQAVTexture *v0, 

                     const TQAVTexture *v1, 

                     const TQAVTexture *v2, 

                     unsigned long flags);

drawContext: A draw context.
v0: A texture vertex.
v1: A texture vertex.
v2: A texture vertex.
flags: A set of triangle flags. See "Triangle Flags Masks" for a complete description of the available flags.

DESCRIPTION

Your TQADrawTriTexture function should draw the texture-mapped triangle determined by the three points specified by the v0 , v1 , and v2 parameters into the draw context specified by the drawContext parameter. The texture used for the mapping is determined by the value of the kQATag_Texture state variable. Features of the triangle are determined by the flags parameter. Currently, this parameter is used to specify an orientation for the triangle.

TQASubmitVerticesGouraud

A drawing engine may define a method to submit Gouraud vertices.



 
typedef void (*TQASubmitVerticesGouraud) (

                     const TQADrawContext *drawContext,

                     unsigned long nVertices,

                     const TQAVGouraud *vertices);

drawContext: A draw context.
nVertices: The number of Gouraud vertices pointed to by the vertices parameter.
vertices: A pointer to an array of Gouraud vertices.

DESCRIPTION

Your TQASubmitVerticesGouraud function should prepare to render a Gouraud-shaded triangular mesh in the draw context specified by the drawContext parameter using the vertices pointed to by the vertices parameter. The actual triangulation and drawing of the mesh does not occur until an application calls the QADrawTriMeshGouraud function.

The calling application is responsible for managing the memory occupied by the Gouraud vertices. Your TQASubmitVerticesGouraud function should not copy the vertex data pointed to by the vertices parameter.

SPECIAL CONSIDERATIONS

The TQASubmitVerticesGouraud method is optional. If your drawing engine does not support triangle meshes, QuickDraw 3D RAVE decomposes a triangle mesh into individual triangles when the user calls the QASubmitVerticesGouraud function to submit a triangle mesh.

There is no QuickDraw 3D RAVE function that an application can use to unsubmit a triangle mesh. Your drawing engine must manage memory in some appropriate manner.

TQASubmitVerticesTexture

A drawing engine may define a method to submit texture vertices. This method is optional and must be supported only by drawing engines that support texture mapping.



 
typedef void (*TQASubmitVerticesTexture) (

                     const TQADrawContext *drawContext,

                     unsigned long nVertices,

                     const TQAVTexture *vertices);

drawContext: A draw context.
nVertices: The number of texture vertices pointed to by the vertices parameter.
vertices: A pointer to an array of texture vertices.

DESCRIPTION

Your TQASubmitVerticesTexture function should prepare to render a texture-mapped triangular mesh in the draw context specified by the drawContext parameter using the vertices pointed to by the vertices parameter. The actual triangulation and drawing of the mesh does not occur until an application calls the QADrawTriMeshTexture function.

The calling application is responsible for managing the memory occupied by the texture vertices. Your TQASubmitVerticesTexture function should not copy the vertex data pointed to by the vertices parameter.

SPECIAL CONSIDERATIONS

The TQASubmitVerticesTexture method is optional. If your drawing engine does not support triangle meshes, QuickDraw 3D RAVE decomposes a triangle mesh into individual triangles when the user calls the QASubmitVerticesTexture function to submit a triangle mesh.

There is no QuickDraw 3D RAVE function that an application can use to unsubmit a triangle mesh. Your drawing engine must manage memory in some appropriate manner.

TQADrawTriMeshGouraud

A drawing engine may define a method to draw a triangle mesh with Gouraud shading.



 
typedef void (*TQADrawTriMeshGouraud) (

                     const TQADrawContext *drawContext,

                     unsigned long nTriangles,

                     const TQAIndexedTriangle *triangles);

drawContext: A draw context.
nTriangle: The number of indexed triangles pointed to by the triangles parameter.
triangles: A pointer to an array of indexed triangles. See "Indexed Triangle Structure" for a description of indexed triangles.

DESCRIPTION

Your TQADrawTriMeshGouraud function should draw, with Gouraud shading, the triangle mesh specified by the triangles parameter into the draw context specified by the drawContext parameter. Each triangle in the mesh is defined by a TQAIndexedTriangle data structure, which contains three indices into the array of Gouraud vertices previously submitted to the draw context by a call to the QASubmitVerticesGouraud function.

SPECIAL CONSIDERATIONS

The TQADrawTriMeshGouraud method is optional. If your drawing engine does not support triangle meshes, QuickDraw 3D RAVE decomposes a triangle mesh into individual triangles when the user calls the QASubmitVerticesGouraud function to submit a triangle mesh.

TQADrawTriMeshTexture

A drawing engine may define a method to draw a texture-mapped triangle mesh. This method is optional and must be supported only by drawing engines that support texture mapping.



 
typedef void (*TQADrawTriMeshTexture) (

                     const TQADrawContext *drawContext,

                     unsigned long nTriangles,

                     const TQAIndexedTriangle *triangles);

drawContext: A draw context.
nTriangle: The number of indexed triangles pointed to by the triangles parameter.
triangles: A pointer to an array of indexed triangles. See "Indexed Triangle Structure" for a description of indexed triangles.

DESCRIPTION

Your TQADrawTriMeshTexture function should draw the texture-mapped triangle mesh specified by the triangles parameter into the draw context specified by the drawContext parameter. Each triangle in the mesh is defined by a TQAIndexedTriangle data structure, which contains three indices into the array of texture vertices previously submitted to the draw context by a call to the QASubmitVerticesTexture function.

SPECIAL CONSIDERATIONS

The TQADrawTriMeshTexture method is optional. If your drawing engine does not support triangle meshes, QuickDraw 3D RAVE decomposes a triangle mesh into individual triangles when the user calls the QASubmitVerticesTexture function to submit a triangle mesh.

TQADrawVGouraud

A drawing engine may define a method to draw Gouraud-shaded objects defined by vertices. This method is optional and must be supported only by drawing engines that do not want calls to QADrawVGouraud to be replaced by calls to the QADrawPoint , QADrawLine , or QADrawTriGouraud methods.



 
typedef void (*TQADrawVGouraud) (

                     const TQADrawContext *drawContext, 

                     unsigned long nVertices, 

                     TQAVertexMode vertexMode, 

                     const TQAVGouraud vertices[], 

                     const unsigned long flags[]);

drawContext: A draw context.
nVertices: The number of vertices contained in the vertices array.
vertexMode: A vertex mode. See "Vertex Modes" for a description of the available vertex modes.
vertices: An array of Gouraud vertices.
flags: An array of triangle flags, or the value NULL . See "Triangle Flags Masks" for a description of the available triangle flags. This parameter is valid only if the vertexMode parameter contains the value kQAVertexMode_Tri , kQAVertexMode_Strip , or kQAVertexMode_Fan .

DESCRIPTION

Your TQADrawVGouraud function should draw the vertices in the array specified by the vertices parameter into the draw context specified by the drawContext parameter, according to the vertex modes flag specified by the vertexMode parameter. For instance, if the value of the vertexMode parameter is kQAVertexMode_Polyline , then the vertices in that array are interpreted as defining a polyline (a set of connected line segments). Gouraud shading should be applied to whatever objects are drawn.

TQADrawVTexture

A drawing engine may define a method to draw texture-mapped objects defined by vertices. This method is optional and must be supported only by drawing engines that support texture mapping and do not want calls to QADrawVTexture to be replaced by calls to the QADrawPoint , QADrawLine , or QADrawTriTexture methods.



 
typedef void (*TQADrawVTexture) (

                     const TQADrawContext *drawContext, 

                     unsigned long nVertices, 

                     TQAVertexMode vertexMode, 

                     const TQAVTexture vertices[], 

                     const unsigned long flags[]);

drawContext: A draw context.
nVertices: The number of vertices contained in the vertices array.
vertexMode: A vertex mode. See "Vertex Modes" for a description of the available vertex modes.
vertices: An array of texture vertices.
flags: An array of triangle flags, or the value NULL . See "Triangle Flags Masks" for a description of the available triangle flags. This parameter is valid only if the vertexMode parameter contains the value kQAVertexMode_Tri , kQAVertexMode_Strip , or kQAVertexMode_Fan .

DESCRIPTION

Your TQADrawVTexture function should draw the vertices in the array specified by the vertices parameter into the draw context specified by the drawContext parameter, according to the vertex modes flag specified by the vertexMode parameter. For instance, if the value of the vertexMode parameter is kQAVertexMode_Polyline , then the vertices in that array are interpreted as defining a polyline (a set of connected line segments). Texture mapping (using the texture determined by the value of the kQATag_Texture state variable) should be applied to whatever objects are drawn.

The vertex modes kQAVertexMode_Point and kQAVertexMode_Line are supported only by drawing engines that support the kQAOptional_OpenGL feature. All other drawing engines should ignore requests to texture map points or lines.

TQADrawBitmap

A drawing engine must define a method to draw bitmaps into a draw context.



 
typedef void (*TQADrawBitmap) (

                     const TQADrawContext *drawContext, 

                     const TQAVGouraud *v, 

                     TQABitmap *bitmap);

drawContext: A draw context.
v: A Gouraud vertex.
bitmap: A pointer to a bitmap (returned by a previous call to QABitmapNew ).

DESCRIPTION

Your TQADrawBitmap function should draw the bitmap specified by the bitmap parameter into the draw context specified by the drawContext parameter, with the upper-left corner of the bitmap located at the point specified by the v parameter. The v parameter can contain negative values in its x or y fields, so you can position upper-left corner of the bitmap outside the draw context rectangle. This allows you to move the bitmap smoothly off any edge of the draw context.

TQARenderStart

A drawing engine must define a method to initialize a draw context before the engine performs any rendering into that context.



 
typedef void (*TQARenderStart) (

                     const TQADrawContext *drawContext, 

                     const TQARect *dirtyRect, 

                     const TQADrawContext *initialContext);

drawContext: A draw context.
dirtyRect: The minimum area of the specified draw context to clear, or the value NULL .
initialContext: A previously cached draw context, or the value NULL .

DESCRIPTION

Your TQARenderStart function should perform any operations necessary to initialize the draw context specified by the drawContext parameter. This includes clearing the z buffer and the color buffers of the draw context. If the value of the initialContext parameter is NULL , then your TQARenderStart function should clear the z buffer to 1.0 and set the color buffers to the values of the kQATag_ColorBG_a , kQATag_ColorBG_r , kQATag_ColorBG_g , and kQATag_ColorBG_b draw context state variables. If, however, the value of the initialContext parameter is not NULL , then your TQARenderStart function should use the previously cached draw context specified by that parameter to initialize the draw context specified by the drawContext parameter.

The dirtyRect parameter indicates the minimum area of the specified draw context that should be cleared on initialization. If the value of the dirtyRect parameter is NULL , the entire draw context is cleared. If the value of the dirtyRect parameter is not NULL , it indicates the rectangle in the draw context to clear. Some drawing engines may exhibit improved performance when an area that is smaller than the entire draw context rectangle is passed. However, the interpretation of the dirtyRect parameter is dependent on the drawing engine, which may choose to initialize the entire draw context. As a result, code calling your QARenderStart function should not use this parameter as a means to avoid clearing all of a draw context or to perform incremental rendering. Instead, that code should use the initialContext parameter to achieve such effects.

SPECIAL CONSIDERATIONS

Applications should call QARenderStart before performing any rendering operations in the specified draw context, and they should call either QARenderEnd to signal the end of rendering operations or QARenderAbort to cancel rendering operations. However, when a drawing engine is performing OpenGL rendering, the QARenderStart function operates just like the OpenGL function glClear . In OpenGL mode, it is not necessary that a call to QARenderStart always be balanced by a matching call to QARenderEnd , and drawing commands may occur at any time.

TQARenderEnd

A drawing engine must define a method to signal the end of any rendering into a draw context.



 
typedef TQAError (*TQARenderEnd) (

                     const TQADrawContext *drawContext, 

                     const TQARect *modifiedRect);

drawContext: A draw context.
modifiedRect: The minimum area of the back buffer of the specified draw context to display, or the value NULL .

DESCRIPTION

Your TQARenderEnd function should perform any operations necessary to display an image rendered into the draw context specified by the drawContext parameter. If the draw context is double buffered, your function should display the back buffer. If the draw context is single buffered, your function should call QAFlush . In either case, your drawing engine should unlock any frame buffers or other memory that is locked, remove any cursor shields, and so forth.

The modifiedRect parameter indicates the minimum area of the back buffer of the specified draw context that should be displayed. If the value of the modifiedRect parameter is NULL , the entire back buffer is displayed. If the value of the modifiedRect parameter is not NULL , it indicates the rectangle in the back buffer to display. Some drawing engines may exhibit improved performance when an area that is smaller than the entire draw context rectangle is passed (to avoid unnecessary pixel copying). However, the interpretation of the modifiedRect parameter is dependent on the drawing engine, which may choose to draw the entire back buffer.

Your TQARenderEnd function should return a result code (of type TQAError ) indicating whether any errors have occurred since the previous call to your TQARenderStart function. If all rendering commands completed successfully, you should return the value kQANoErr . If you return any other value, the code that called QARenderEnd should assume that the rendered image is incorrect.

SPECIAL CONSIDERATIONS

TQARenderAbort

A drawing engine must define a method to cancel any asynchronous drawing requests for a draw context.



 
typedef TQAError (*TQARenderAbort) ( 

                     const TQADrawContext *drawContext);

drawContext: A draw context.

DESCRIPTION

Your TQARenderAbort function should immediately stop processing any asynchronous drawing command it is currently processing and it should discard any queued commands associated with the draw context specified by the drawContext parameter.

Your TQARenderAbort function should return a result code (of type TQAError ) indicating whether any errors have occurred since the previous call to your TQARenderStart function. If all rendering commands completed successfully, you should return the value kQANoErr . If you return any other value, the code that called QARenderEnd should assume that the rendered image is incorrect.

TQAFlush

A drawing engine must define a method to flush a draw context.



 
typedef TQAError (*TQAFlush) (const TQADrawContext *drawContext);

drawContext: A draw context.

DESCRIPTION

Your TQAFlush function should cause your drawing engine to begin rendering all drawing commands that are queued in a buffer awaiting processing for the draw context specified by the drawContext parameter. QuickDraw 3D RAVE allows a drawing engine to buffer as many drawing commands as desired. Accordingly, the successful completion of a drawing command (such as QADrawPoint ) does not guarantee that the specified object is visible on the screen. An application can call QAFlush to have your drawing engine start processing queued commands. Note, however, that QAFlush is not a blocking call--that is, the successful completion of QAFlush does not guarantee that all buffered commands have been processed. Calling QAFlush guarantees only that all queued commands will eventually be processed.

Typically, applications should occasionally call QAFlush to update the screen image during a lengthy set of rendering operations in a single-buffered draw context. QAFlush has no visible effect when called on a double-buffered draw context, but it does initiate rendering to the back buffer.

Your TQAFlush function should return a result code (of type TQAError ) indicating whether any errors have occurred since the previous call to your TQARenderStart function. If all rendering commands completed successfully, you should return the value kQANoErr . If you return any other value, the code that called QAFlush should assume that the rendered image is incorrect.

TQASync

A drawing engine must define a method to synchronize a draw context.



 
typedef TQAError (*TQASync) (const TQADrawContext *drawContext);

drawContext: A draw context.

DESCRIPTION

Your TQASync function should operate just like your TQAFlush function, except that it should wait until all queued drawing commands have been processed before returning. See the description of TQAFlush [link] for complete details.

TQAGetNoticeMethod

A drawing engine must define a method to return the notice method of a draw context.



 
typedef TQAError (*TQAGetNoticeMethod) ( 

                     const TQADrawContext *drawContext, 

                     TQAMethodSelector method, 

                     TQANoticeMethod *completionCallBack, 

                     void **refCon);

drawContext: A draw context.
method: A method selector. See "Notice Method Selectors" for a description of the available method selectors.
completionCallBack: On exit, a pointer to the current draw context notice method of the specified type.
refCon: On exit, the reference constant of the specified notice method.

DESCRIPTION

Your TQAGetNoticeMethod function should return, in the completionCallBack parameter, a pointer to the current notice method of the draw context specified by the drawContext parameter that has the type specified by the method parameter. TQAGetNoticeMethod should also return, in the refCon parameter, the reference constant associated with that notice method.

TQASetNoticeMethod

A drawing engine must define a method to set the notice method of a draw context.



 
typedef TQAError (*TQASetNoticeMethod) (

                     const TQADrawContext *drawContext, 

                     TQAMethodSelector method, 

                     TQANoticeMethod completionCallBack, 

                     void *refCon);

drawContext: A draw context.
method: A method selector. See "Notice Method Selectors" for a description of the available method selectors.
completionCallBack: A pointer to the desired draw context notice method of the specified type. See "Notice Methods" for information about notice methods.
refCon: A reference constant for the specified notice method. This value is passed unchanged to the notice method when it is called.

DESCRIPTION

Your TQASetNoticeMethod function should set the notice method of type method of the draw context specified by the drawContext parameter to the function pointed to by the completionCallBack parameter. TQASetNoticeMethod should also set the reference constant of that method to the value specified by the refCon parameter.